JSON (JavaScript Object Notation) is one of the most commonly used data formats in Flutter applications. It is widely used for exchanging structured data between a Flutter app and a backend API. Flutter applications can decode JSON received from APIs, convert JSON into Dart objects, and encode Dart objects into JSON when sending data to a server.
JSON stands for JavaScript Object Notation. It is a lightweight, text-based format used to represent structured data.
Although JSON originated from JavaScript, it is language-independent and is commonly used by APIs, mobile applications, web applications, and backend services.
{
"id": 101,
"name": "Rahul",
"email": "[email protected]",
"age": 25
}
In this example, id, name, email, and age are JSON keys, while their associated values are the actual data.
Flutter applications frequently communicate with REST APIs. Most APIs return data in JSON format, so Flutter developers need to understand how to read, process, create, and send JSON data.
JSON supports several basic data types.
| JSON Type | Example | Dart Equivalent |
|---|---|---|
| String | "Flutter" |
String |
| Number | 25 |
int or double |
| Boolean | true |
bool |
| Null | null |
null |
| Object | {"name":"Rahul"} |
Map |
| Array | ["Flutter","Dart"] |
List |
A JSON object contains key-value pairs enclosed in curly braces {}.
{
"name": "Amit",
"age": 28,
"isStudent": false
}
A JSON array contains multiple values and is represented using square brackets [].
[
"Flutter",
"Dart",
"Firebase",
"REST API"
]
An array can also contain multiple JSON objects.
[
{
"id": 1,
"name": "Rahul"
},
{
"id": 2,
"name": "Priya"
},
{
"id": 3,
"name": "Amit"
}
]
Flutter uses Dart, and Dart provides the dart:convert library for encoding and decoding JSON.
import 'dart:convert';
The two most important functions are:
jsonDecode() - Converts JSON text into Dart data.jsonEncode() - Converts Dart data into JSON text.
Decoding means converting a JSON string into a Dart data structure.
import 'dart:convert';
const jsonString = '''
{
"name": "Rahul",
"age": 25
}
''';
final data = jsonDecode(jsonString);
print(data['name']);
print(data['age']);
Rahul
25
Flutter's documentation describes manual JSON decoding using the built-in dart:convert library and jsonDecode(). :contentReference[oaicite:0]{index=0}
The result of jsonDecode() is dynamic, so the developer should convert it to an appropriate Dart type when working with structured data.
final Map data =
jsonDecode(jsonString) as Map;
print(data['name']);
const jsonString = '''
{
"id": 101,
"name": "Rahul",
"email": "[email protected]"
}
''';
final data = jsonDecode(jsonString)
as Map;
print(data['id']);
print(data['name']);
print(data['email']);
When the JSON response contains an array, decode it into a Dart list.
const jsonString = '''
[
{
"id": 1,
"name": "Rahul"
},
{
"id": 2,
"name": "Priya"
}
]
''';
final List users = jsonDecode(jsonString);
for (final user in users) {
print(user['name']);
}
A JSON object can be represented in Dart as a Map.
final Map user = {
'id': 1,
'name': 'Rahul',
'age': 25,
};
A JSON array can be represented as a Dart List.
final List skills = [
'Flutter',
'Dart',
'Firebase',
];
Encoding means converting Dart data into a JSON string.
import 'dart:convert';
final user = {
'id': 1,
'name': 'Rahul',
'email': '[email protected]',
};
final jsonString = jsonEncode(user);
print(jsonString);
{"id":1,"name":"Rahul","email":"[email protected]"}
final skills = [
'Flutter',
'Dart',
'Firebase',
];
final jsonString = jsonEncode(skills);
print(jsonString);
["Flutter","Dart","Firebase"]
A common Flutter API flow looks like this:
Flutter Application
|
| HTTP Request
v
Backend API
|
| JSON Response
v
Flutter Application
|
| jsonDecode()
v
Dart Object / Model
|
v
Flutter UI
The http package can be used to fetch JSON data from an API.
import 'dart:convert';
import 'package:http/http.dart' as http;
Future fetchData() async {
final response = await http.get(
Uri.parse(
'https://jsonplaceholder.typicode.com/albums/1',
),
);
if (response.statusCode == 200) {
final data = jsonDecode(response.body)
as Map;
print(data['title']);
} else {
throw Exception('Failed to load data');
}
}
Flutter's networking cookbook follows this general pattern: make the request, check the response status, decode the JSON body, and convert it into a Dart object. :contentReference[oaicite:1]{index=1}
Although accessing JSON directly through maps is convenient for small examples, model classes are usually easier to maintain as applications become larger.
Model classes provide:
Suppose an API returns this JSON:
{
"id": 1,
"name": "Rahul",
"email": "[email protected]"
}
Create a corresponding Dart class:
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
}
The fromJson() factory constructor converts a JSON map into a Dart object.
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
email: json['email'] as String,
);
}
}
Flutter's JSON documentation recommends model classes with fromJson() and toJson() for stronger type safety and cleaner serialization logic. :contentReference[oaicite:2]{index=2}
const jsonString = '''
{
"id": 1,
"name": "Rahul",
"email": "[email protected]"
}
''';
final Map data =
jsonDecode(jsonString);
final user = User.fromJson(data);
print(user.name);
print(user.email);
The toJson() method converts a Dart object into a map that can be encoded into JSON.
class User {
final int id;
final String name;
final String email;
const User({
required this.id,
required this.name,
required this.email,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
email: json['email'] as String,
);
}
Map toJson() => {
'id': id,
'name': name,
'email': email,
};
}
final user = User(
id: 1,
name: 'Rahul',
email: '[email protected]',
);
final jsonString = jsonEncode(user.toJson());
print(jsonString);
import 'dart:convert';
class Product {
final int id;
final String name;
final double price;
final bool available;
const Product({
required this.id,
required this.name,
required this.price,
required this.available,
});
factory Product.fromJson(Map json) {
return Product(
id: json['id'] as int,
name: json['name'] as String,
price: (json['price'] as num).toDouble(),
available: json['available'] as bool,
);
}
Map toJson() {
return {
'id': id,
'name': name,
'price': price,
'available': available,
};
}
}
void main() {
const jsonString = '''
{
"id": 1,
"name": "Flutter Course",
"price": 4999.0,
"available": true
}
''';
final data = jsonDecode(jsonString)
as Map;
final product = Product.fromJson(data);
print(product.name);
print(product.price);
final jsonOutput = jsonEncode(product.toJson());
print(jsonOutput);
}
When an API returns multiple objects, convert each JSON object into a model object.
final List data = jsonDecode(response.body);
final List products = data
.map(
(item) => Product.fromJson(
item as Map,
),
)
.toList();
ListView.builder(
itemCount: products.length,
itemBuilder: (context, index) {
final product = products[index];
return ListTile(
title: Text(product.name),
subtitle: Text('₹${product.price}'),
trailing: product.available
? const Icon(Icons.check)
: const Icon(Icons.close),
);
},
)
Real-world APIs often contain nested JSON objects.
{
"id": 1,
"name": "Rahul",
"address": {
"street": "MG Road",
"city": "Mumbai",
"zipCode": "400001"
}
}
class Address {
final String street;
final String city;
final String zipCode;
const Address({
required this.street,
required this.city,
required this.zipCode,
});
factory Address.fromJson(Map json) {
return Address(
street: json['street'] as String,
city: json['city'] as String,
zipCode: json['zipCode'] as String,
);
}
Map toJson() => {
'street': street,
'city': city,
'zipCode': zipCode,
};
}
class User {
final int id;
final String name;
final Address address;
const User({
required this.id,
required this.name,
required this.address,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
address: Address.fromJson(
json['address'] as Map,
),
);
}
Map toJson() => {
'id': id,
'name': name,
'address': address.toJson(),
};
}
JSON can contain arrays inside objects.
{
"id": 1,
"name": "Rahul",
"skills": [
"Flutter",
"Dart",
"Firebase"
]
}
class User {
final int id;
final String name;
final List skills;
const User({
required this.id,
required this.name,
required this.skills,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
skills: List.from(
json['skills'] as List,
),
);
}
}
API responses may contain null values. Dart's null safety should be considered when defining models.
{
"id": 1,
"name": "Rahul",
"phone": null
}
class User {
final int id;
final String name;
final String? phone;
const User({
required this.id,
required this.name,
this.phone,
});
factory User.fromJson(Map json) {
return User(
id: json['id'] as int,
name: json['name'] as String,
phone: json['phone'] as String?,
);
}
}
Sometimes an API field may be missing. A default value can be used when appropriate.
class User {
final String name;
final String role;
const User({
required this.name,
required this.role,
});
factory User.fromJson(Map json) {
return User(
name: json['name'] as String? ?? 'Unknown',
role: json['role'] as String? ?? 'User',
);
}
}
JSON numbers may represent integers or floating-point values. Using num can be useful when the API may return either representation.
final price = (json['price'] as num).toDouble();
This is useful when an API may return values such as 4999 or 4999.50.
{
"name": "Flutter Course",
"isActive": true
}
final isActive = json['isActive'] as bool;
JSON does not have a dedicated DateTime type. APIs commonly send dates as strings.
{
"createdAt": "2026-09-19T10:30:00Z"
}
Convert the value to a Dart DateTime:
final createdAt = DateTime.parse(
json['createdAt'] as String,
);
JSON parsing can fail when the response is malformed or has an unexpected structure.
try {
final data = jsonDecode(response.body);
print(data);
} catch (e) {
print('Invalid JSON: $e');
}
Always be careful about the data types returned by an API.
final age = json['age'];
if (age is int) {
print('Age: $age');
} else {
print('Invalid age value');
}
FutureBuilder can be used to display JSON data after an asynchronous API request completes.
FutureBuilder(
future: fetchProduct(),
builder: (context, snapshot) {
if (snapshot.connectionState ==
ConnectionState.waiting) {
return const CircularProgressIndicator();
}
if (snapshot.hasError) {
return Text('Error: ${snapshot.error}');
}
if (!snapshot.hasData) {
return const Text('No product found');
}
final product = snapshot.data!;
return Column(
children: [
Text(product.name),
Text('₹${product.price}'),
],
);
},
)
JSON is not only used for API responses. It is also commonly used as the request body when sending data to an API.
import 'dart:convert';
import 'package:http/http.dart' as http;
Future createUser() async {
final user = {
'name': 'Rahul',
'email': '[email protected]',
};
final response = await http.post(
Uri.parse('https://example.com/api/users'),
headers: {
'Content-Type': 'application/json',
},
body: jsonEncode(user),
);
print(response.statusCode);
}
Flutter's networking documentation uses jsonEncode() to convert Dart data into a JSON request body for POST operations. :contentReference[oaicite:3]{index=3}
APIs may return errors in JSON format.
{
"success": false,
"message": "Invalid email address",
"errors": {
"email": "Please enter a valid email"
}
}
final data = jsonDecode(response.body)
as Map;
final message = data['message'] as String?;
print(message);
For complex APIs, it can be useful to create a separate model for API response information.
class ApiResponse {
final bool success;
final String message;
const ApiResponse({
required this.success,
required this.message,
});
factory ApiResponse.fromJson(
Map json,
) {
return ApiResponse(
success: json['success'] as bool? ?? false,
message: json['message'] as String? ?? '',
);
}
}
| Operation | Description | Common Function |
|---|---|---|
| Decoding | JSON string → Dart data | jsonDecode() |
| Encoding | Dart data → JSON string | jsonEncode() |
| Deserialization | JSON data → Dart model object | fromJson() |
| Serialization | Dart model object → JSON-compatible data | toJson() |
Manual serialization means writing fromJson() and toJson() methods yourself.
class Product {
final int id;
final String name;
const Product({
required this.id,
required this.name,
});
factory Product.fromJson(Map json) {
return Product(
id: json['id'] as int,
name: json['name'] as String,
);
}
Map toJson() => {
'id': id,
'name': name,
};
}
Manual serialization is simple and useful for smaller projects or prototypes. Flutter's official documentation describes this approach using dart:convert. :contentReference[oaicite:4]{index=4}
For medium and large applications with many models, manually writing JSON serialization code can become repetitive. Flutter's documentation discusses code-generation approaches such as json_serializable for larger projects. :contentReference[oaicite:5]{index=5}
flutter pub add json_annotation
flutter pub add --dev build_runner
flutter pub add --dev json_serializable
import 'package:json_annotation/json_annotation.dart';
part 'user.g.dart';
@JsonSerializable()
class User {
final String name;
final String email;
User({
required this.name,
required this.email,
});
factory User.fromJson(
Map json,
) => _$UserFromJson(json);
Map toJson() => _$UserToJson(this);
}
After creating a json_serializable model, generate the serialization code using:
dart run build_runner build --delete-conflicting-outputs
For continuous generation during development:
dart run build_runner watch --delete-conflicting-outputs
Flutter's JSON documentation provides these commands for generating the .g.dart serialization files. :contentReference[oaicite:6]{index=6}
Sometimes an API uses a different naming convention from your Dart model.
For example, an API may return:
{
"first_name": "Rahul"
}
With json_serializable, @JsonKey can map the JSON key to a Dart property.
@JsonKey(name: 'first_name')
final String firstName;
Large APIs can contain multiple nested objects. Each nested object can have its own model class.
class Address {
final String city;
Address({
required this.city,
});
factory Address.fromJson(
Map json,
) => Address(
city: json['city'] as String,
);
Map toJson() => {
'city': city,
};
}
JSON data can be displayed using standard Flutter widgets.
Card(
child: ListTile(
title: Text(product.name),
subtitle: Text('₹${product.price}'),
trailing: Text(
product.available ? 'Available' : 'Unavailable',
),
),
)
API Server
↓
JSON Response
↓
http.Response
↓
response.body
↓
jsonDecode()
↓
Map / List
↓
Model.fromJson()
↓
Dart Object
↓
Application State
↓
Flutter Widget
↓
User Interface
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
class Product {
final int id;
final String name;
final double price;
const Product({
required this.id,
required this.name,
required this.price,
});
factory Product.fromJson(
Map json,
) {
return Product(
id: json['id'] as int,
name: json['name'] as String,
price: (json['price'] as num).toDouble(),
);
}
}
Future> fetchProducts() async {
final response = await http.get(
Uri.parse('https://example.com/api/products'),
headers: {
'Accept': 'application/json',
},
);
if (response.statusCode != 200) {
throw Exception('Failed to load products');
}
final List data =
jsonDecode(response.body);
return data
.map(
(item) => Product.fromJson(
item as Map,
),
)
.toList();
}
class ProductScreen extends StatefulWidget {
const ProductScreen({super.key});
@override
State createState() =>
_ProductScreenState();
}
class _ProductScreenState
extends State {
late Future> productsFuture;
@override
void initState() {
super.initState();
productsFuture = fetchProducts();
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: const Text('Products'),
),
body: FutureBuilder>(
future: productsFuture,
builder: (context, snapshot) {
if (snapshot.connectionState ==
ConnectionState.waiting) {
return const Center(
child: CircularProgressIndicator(),
);
}
if (snapshot.hasError) {
return Center(
child: Text('Error: ${snapshot.error}'),
);
}
final products = snapshot.data ?? [];
if (products.isEmpty) {
return const Center(
child: Text('No products found'),
);
}
return ListView.builder(
itemCount: products.length,
itemBuilder: (context, index) {
final product = products[index];
return ListTile(
title: Text(product.name),
subtitle: Text(
'₹${product.price}',
),
);
},
);
},
),
);
}
}
Large JSON responses can require significant processing. For very large datasets, expensive JSON parsing can be moved to another isolate so the user interface remains responsive.
import 'dart:convert';
import 'package:flutter/foundation.dart';
List> parseJson(
String responseBody,
) {
final data = jsonDecode(responseBody) as List;
return data
.map(
(item) => item as Map,
)
.toList();
}
final result = await compute(
parseJson,
response.body,
);
Flutter's networking documentation demonstrates using compute() to move JSON parsing work to another isolate when appropriate for large responses. :contentReference[oaicite:7]{index=7}
jsonDecode() to decode JSON strings.jsonEncode() to encode Dart data.fromJson() to create model objects.toJson() to convert models into JSON-compatible maps.
dart:convert.jsonDecode() without checking the response.null values.
| JSON Structure | Dart Structure | Example |
|---|---|---|
| Object | Map |
User information |
| Array | List |
List of users |
| Nested Object | Nested Map or Model | User address |
| Nested Array | List inside Map/Model | User skills |
Create a Flutter application that consumes a product API.
Product model.Product.fromJson().List.ListView.builder.toJson() for the product model.
jsonDecode()?jsonEncode()?fromJson()?toJson()?json_serializable?
| Concept | Key Point |
|---|---|
| JSON | Lightweight format for structured data exchange |
dart:convert |
Dart library containing JSON encoding and decoding utilities |
jsonDecode() |
Converts JSON text into Dart data |
jsonEncode() |
Converts Dart data into JSON text |
fromJson() |
Creates a Dart model from JSON data |
toJson() |
Converts a Dart model into JSON-compatible data |
| Map | Represents a JSON object |
| List | Represents a JSON array |
| Model Class | Provides structured representation of API data |
| json_serializable | Generates JSON serialization code |
compute() |
Can move expensive parsing work to another isolate |
To learn Flutter development through structured training, visit the JustAcademy Flutter Training Course.
To register for a Flutter course demonstration, visit the JustAcademy Flutter Course Demo Registration page.
JSON is a fundamental part of Flutter application development because it provides a standard way to exchange structured data between Flutter applications and backend services. Developers should understand JSON objects, arrays, data types, jsonDecode(), jsonEncode(), model classes, fromJson(), toJson(), nested JSON, nullable values, error handling, and JSON serialization.
For small projects, manual serialization with dart:convert can be straightforward. For medium and large applications, code-generation approaches such as json_serializable can reduce repetitive serialization code. :contentReference[oaicite:8]{index=8}
The basic JSON workflow can be remembered as:
API Response
↓
JSON String
↓
jsonDecode()
↓
Map / List
↓
fromJson()
↓
Dart Model
↓
Application State
↓
Flutter UI
